home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CD ROM Paradise Collection 4
/
CD ROM Paradise Collection 4 1995 Nov.iso
/
program
/
recio212.zip
/
spec.txt
< prev
next >
Wrap
Text File
|
1995-01-29
|
79KB
|
2,671 lines
Title: SPECIFICATION OF C LANGUAGE RECIO LIBRARY
Copyright: (C) 1994-1995, William Pierpoint
Version: 2.12
Date: January 29, 1995
1.0 RECORD INPUT/OUTPUT <recio.h>
1.1 Introduction
The header <recio.h> declares two types, several macros, and many functions
for performing line oriented input and output.
1.1.1 Record Streams
Input and output are mapped into logical data record streams. A record
stream is an ordered sequence of characters composed into records, each
record consisting of zero or more characters plus a terminating record
delimiter character. The terminating record delimiter for a file is the
newline character.
Each record consists of zero or more fields. The record may be broken
into fields in two different ways: (1) character delimited and (2) column
delimited. For character delimited fields, each field consists of zero or
more characters plus a terminating field delimiter character or, for the
last field in the record, the record delimiter character. For column
delimited fields, each field consists of one or more characters delimited
by a single column position for fields consisting of one character, or by
beginning and ending column positions for fields consisting of one or more
characters.
Four types of fields are defined: (1) character, (2) text, (3) numeric, and
(4) time. A character field consists of a single character. A text field
consists of a sequence of zero or more characters delimited at each end by an
optional text delimiter character. A numeric field consists of a sequence of
one or more characters from the set of valid characters for the number type
(integral or floating point) and radix. A time field consists of a sequence
of one or more characters from the set of valid characters for the time type,
delimited according to a specified format string.
1.1.2 Types
The types are
REC
which is an object type capable of recording all information needed to
control a record stream used for line oriented input or output, including
its file pointer, pointers to its associated record and field buffers, field
and text delimiting characters, an error indicator that records whether
an error has occurred, and an end-of-file indicator that records whether
the end of the file has been reached; and
rpos_t
which is an object type capable of recording all the information needed to
specify uniquely any field position within a record.
1.1.3 Macros
The macros are
RECBUFSIZ
FLDBUFSIZ
which expand to integral constant expressions, which are the initial
sizes of the record buffer and the field buffer;
RECFLDCH
RECTXTCH
which expand to integral constant expressions, which are the default
values of the characters used to separate the fields and delimit text
in a record and whose default value shall correspond to the value of
the space character;
ROPEN_MAX
which expands to an integral constant expression that is the maximum
number of files that can be open simultaneously;
RECIN
RECOUT
RECERR
which expand to an integral constant expression that is the context
number for the recin record stream that gets input from the <stdio.h>
standard input stream stdin, the recout record stream that puts output
to the <stdio.h> standard output stream stdout, and the recerr record
stream that puts output to the <stdio.h> standard error stream stderr.
1.1.4 Expressions
The expressions are
recin
recout
recerr
which are of type "pointer to REC" that points to the REC object associated
with the <stdio.h> FILE objects stdin (standard input stream), stdout
(standard output stream), and stderr (standard error stream). The recin,
recout, and recerr record streams are always open and are included in the
count of ROPEN_MAX.
1.2 Record Access Functions
1.2.1 The rclose Function
Synopsis
#include <recio.h>
void rclose(REC *rp);
Description
The rclose function causes the record stream pointed to by rp and the
associated file to be closed. Any unread data is discarded. The record
stream is disassociated from the file. If associated buffers were
automatically allocated, they are deallocated.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rclose function returns no value.
1.2.2 The rcloseall Function
Synopsis
#include <recio.h>
int rcloseall(void);
Description
The rcloseall function causes all the open record streams, and all the
files associated with the open record streams, to be closed. Any unread
data is discarded. Each record stream is disassociated from its file.
If associated buffers were automatically allocated, they are deallocated.
Returns
The rcloseall function returns the number of record streams successfully
closed.
1.2.3 The ropen Function
Synopsis
#include <recio.h>
REC *ropen(const char *filename, const char *mode);
Description
The ropen function opens the file whose name is the string pointed to by
filename, and associates a record stream with it. The argument mode
points to a string whose first letter is:
"r" - open text file for input
"w" - open text file for output
"a" - open text file for append
When successfully opened, the error and end-of-file indicators for the
record stream are clear. If an error occurs, errno is set to one of the
error reporting macros as defined in <errno.h>, the callback error function
is called (except when the file associated with filename is not able to be
opened), and a null pointer is returned.
Returns
The ropen function returns a pointer to the object controlling the record
stream. If the open operation fails, ropen returns a null pointer.
1.2.4 The rsetfldsiz Function
Synopsis
#include <recio.h>
void rsetfldsiz(REC *rp, size_t fldsize);
Description
The rsetfldsiz function reallocates the field buffer associated with the
record stream pointed to by rp to the new size of fldsize.
The rsetfldsiz function may be used only after the record stream pointed
to by rp has been opened and before any data is read into the record
buffer. Data is read into the record buffer by the function rgetrec,
or by calling a function that either skips a field or gets data from a
field. If rsetfldsiz is not used, the initial size of the field buffer
is set by the value of the macro FLDBUFSIZ.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetfldsiz function returns no value.
1.2.5 The rsetrecsiz Function
Synopsis
#include <recio.h>
void rsetrecsiz(REC *rp, size_t recsize);
Description
The rsetrecsiz function reallocates the record buffer associated with the
record stream pointed to by rp to the new size of recsize.
The rsetrecsiz function may be used only after the record stream pointed
to by rp has been opened and before any data is read into the record
buffer. Data is read into the record buffer by the function rgetrec,
or by calling a function that either skips a field or gets data from a
field. If rsetrecsiz is not used, the initial size of the field buffer
is set by the value of the macro RECBUFSIZ.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetrecsiz function returns no value.
1.3 Character Delimited Field Input Functions
The character delimited field input functions use a character (such as
a comma or space) to determine where each field begins and ends.
1.3.1 The rbgeti Function
Synopsis
#include <recio.h>
int rbgeti(REC *rp, int base);
Description
The rbgeti function reads a field consisting of one integral number
represented by the radix determined by the value of base from the input
record stream pointed to by rp. Any leading or trailing white space
in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rbgeti function returns a signed integer from the input record
stream pointed to by rp. If an attempt is made to read beyond the
end-of-record, if the field is empty, or if there is an illegal character
in the field, the error indicator for the record stream is set, and rbgeti
returns zero. If the record stream is at end-of-file (end-of-file indicator
set), rbgeti returns zero. If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rbgeti returns zero.
1.3.2 The rbgetl Function
Synopsis
#include <recio.h>
long rbgetl(REC *rp, int base);
Description
The rbgetl function reads a field consisting of one integral number
represented by the radix determined by the value of base from the input
record stream pointed to by rp. Any leading or trailing white space
in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rbgetl function returns a signed long from the input record stream
pointed to by rp. If an attempt is made to read beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field,
the error indicator for the record stream is set, and rbgetl returns zero
(0L). If the record stream is at end-of-file (end-of-file indicator set),
rbgetl returns zero (0L). If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rbgetl returns
zero (0L).
1.3.3 The rbgetui Function
Synopsis
#include <recio.h>
unsigned int rbgetui(REC *rp, int base);
Description
The rbgetui function reads a field consisting of one non-negative integral
number represented by the radix determined by the value of base from the
input record stream pointed to by rp. Any leading or trailing white space
in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rbgetui function returns an unsigned integer from the input record
stream pointed to by rp. If an attempt is made to read beyond the
end-of-record, if the field is empty, or if there is an illegal character
in the field, the error indicator for the record stream is set, and rbgetui
returns zero. If the record stream is at end-of-file (end-of-file indicator
set), rbgetui returns zero. If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rbgetui returns zero.
1.3.4 The rbgetul Function
Synopsis
#include <recio.h>
unsigned long rbgetul(REC *rp, int base);
Description
The rbgetul function reads a field consisting of one non-negative integral
number represented by the radix determined by the value of base from the
input record stream pointed to by rp. Any leading or trailing white space
in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rbgetul function returns an unsigned long from the input record stream
pointed to by rp. If an attempt is made to read beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field,
the error indicator for the record stream is set, and rbgetul returns zero
(0L). If the record stream is at end-of-file (end-of-file indicator set),
rbgetul returns zero (0L). If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rbgetul returns
zero (0L).
1.3.5 The rgetc Function
Synopsis
#include <recio.h>
int rgetc(REC *rp);
Description
The rgetc function reads a field consisting of one non-white space
character from the input record stream pointed to by rp. Any leading
or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns EOF.
Returns
The rgetc function returns a character from a single non-white
space character field in the input record stream pointed to by rp.
If an attempt is made to read beyond the end-of-record, or if there
is more than or less than one non-white character in the field, the
error indicator for the record stream is set, and rgetc returns EOF. If the
record stream is at end-of-file (end-of-file indicator set), rgetc returns
EOF. If a previous error has occurred on the record stream that has not been
cleared (error indicator set), rgetc returns EOF.
1.3.6 The rgetd Function
Synopsis
#include <recio.h>
double rgetd(REC *rp);
Description
The rgetd function reads a field consisting of one floating point
number from the input record stream pointed to by rp. Any leading
or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rgetd function returns a double precision floating point number
from the input record stream pointed to by rp. If an attempt is made
to read beyond the end-of-record, if the field is empty, or if there
is an illegal character in the field, the error indicator for the
record stream is set, and rgetd returns zero (0.0). If the record stream is
at end-of-file (end-of-file indicator set), rgetd returns zero (0.0). If a
previous error has occurred on the record stream that has not been cleared
(error indicator set), rgetd returns zero (0.0).
1.3.7 The rgetf Function
Synopsis
#include <recio.h>
float rgetf(REC *rp);
Description
The rgetf function reads a field consisting of one floating point
number from the input record stream pointed to by rp. Any leading
or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rgetf function returns a single precision floating point number
from the input record stream pointed to by rp. If an attempt is made
to read beyond the end-of-record, if the field is empty, or if there
is an illegal character in the field, the error indicator for the
record stream is set, and rgetf returns zero (0.0). If the record stream is
at end-of-file (end-of-file indicator set), rgetf returns zero (0.0). If a
previous error has occurred on the record stream that has not been cleared
(error indicator set), rgetf returns zero (0.0).
1.3.8 The rgeti Function
Synopsis
#include <recio.h>
int rgeti(REC *rp);
Description
The rgeti function reads a field consisting of one integral
number from the input record stream pointed to by rp. Any leading
or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rgeti function returns a signed integer from the input record
stream pointed to by rp. If an attempt is made to read beyond the
end-of-record, if the field is empty, or if there is an illegal character
in the field, the error indicator for the record stream is set, and rgeti
returns zero. If the record stream is at end-of-file (end-of-file indicator
set), rgeti returns zero. If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rgeti returns zero.
1.3.9 The rgetl Function
Synopsis
#include <recio.h>
long rgetl(REC *rp);
Description
The rgetl function reads a field consisting of one integral number
from the input record stream pointed to by rp. Any leading or trailing
white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rgetl function returns a signed long from the input record stream
pointed to by rp. If an attempt is made to read beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field,
the error indicator for the record stream is set, and rgetl returns zero
(0L). If the record stream is at end-of-file (end-of-file indicator set),
rgetl returns zero (0L). If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rgetl returns zero
(0L).
1.3.10 The rgets Function
Synopsis
#include <recio.h>
char *rgets(REC *rp);
Description
The rgets function reads a field consisting of one text string from the
input record stream pointed to by rp. Any leading white space before the
text delimiter and any trailing white space after the text delimiter in
the field is ignored. The text delimiters are not returned as part of
the string.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and the function returns a pointer to
an empty string.
Returns
The rgets function returns a pointer to a character array from the input
record stream pointed to by rp. If an attempt is made to read beyond the
end-of-record, the error indicator for the record stream is set, and rgets
returns a pointer to an empty string. If the record stream is at end-of-file
(end-of-file indicator set), rgets returns a pointer to an empty string. If
a previous error has occurred on the record stream that has not been cleared
(error indicator set), rgets returns a pointer to an empty string.
1.3.11 The rgett Function
Synopsis
#include <recio.h>
time_t rgett(REC *rp);
Description
The rgett function reads a field consisting of one time of type time_t from
input record stream pointed to by rp. Any leading or trailing white space
in the field is ignored.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and the function returns (time_t)-1.
Returns
The rgett function returns a time of type time_t. If an attempt is made to
read beyond the end-of-record, the error indicator for the record stream is
set, and rgett returns (time_t)-1. If the record stream is at end-of-file
(end-of-file indicator set), rgett returns (time_t)-1. If a previous error
has occurred on the record stream that has not been cleared (error indicator
set), rgett returns (time_t)-1.
1.3.12 The rgettm Function
Synopsis
#include <recio.h>
struct tm rgettm(REC *rp);
Description
The rgettm function reads a field consisting of one time of type struct tm
from input record stream pointed to by rp. Any leading or trailing white
space in the field is ignored.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and the function returns an implementation
defined value.
Returns
The rgettm function returns a time of type struct tm. If an attempt is made
to read beyond the end-of-record, the error indicator for the record stream
is set, and rgettm returns an implementation defined value. If the record
stream is at end-of-file (end-of-file indicator set), rgettm returns an
implementation defined value. If a previous error has occurred on the
record stream that has not been cleared (error indicator set), rgettm returns
an implementation defined value.
1.3.13 The rgetui Function
Synopsis
#include <recio.h>
unsigned int rgetui(REC *rp);
Description
The rgetui function reads a field consisting of one non-negative
integral number from the input record stream pointed to by rp. Any
leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rgetui function returns an unsigned integer from the input record
stream pointed to by rp. If an attempt is made to read beyond the
end-of-record, if the field is empty, or if there is an illegal character
in the field, the error indicator for the record stream is set, and rgetui
returns zero. If the record stream is at end-of-file (end-of-file indicator
set), rgetui returns zero. If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rgetui returns zero.
1.3.14 The rgetul Function
Synopsis
#include <recio.h>
unsigned long rgetul(REC *rp);
Description
The rgetul function reads a field consisting of one non-negative
integral number from the input record stream pointed to by rp. Any
leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and the function returns zero (0L).
Returns
The rgetul function returns an unsigned long from the input record stream
pointed to by rp. If an attempt is made to read beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field,
the error indicator for the record stream is set, and rgetul returns zero
(0L). If the record stream is at end-of-file (end-of-file indicator set),
rgetul returns zero (0L). If a previous error has occurred on the record
stream that has not been cleared (error indicator set), rgetul returns zero
(0L).
1.3.15 The rsetfldch Function
Synopsis
#include <recio.h>
void rsetfldch(REC *rp, int ch);
Description
The rsetfldch function sets the field delimiter to the character ch
for the record stream pointed to by rp. If the character ch is the
space character ' ', then the field is delimited by any white-space,
and multiple contiguous white space characters are treated as a single
delimiter. If the character ch is other than the space character, then
multiple contiguous field delimiters are treated as a series of empty
fields.
If rsetfldch is not called, the field delimiter is set by the value of
the macro RECFLDCH.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetfldch function returns no value.
1.3.16 The rsettmfmt Function
Synopsis
#include <recio.h>
void rsettmfmt(REC *rp, char *fmt);
Description
The rsettmfmt function sets the time format according to the string fmt
for the record stream pointed to by rp.
Time formats are specified using a subset of the specifiers from the
ANSI-C strftime function. Supported specifiers are:
%d - day of month (1-31)
%H - hour from 24-hour clock (0-23)
%m - month (1-12)
%M - minute (0-59)
%s - second (0-61)
%y - year without century (00-99)
%Y - year with century (e.g. 1994)
If the rsettmfmt function is not called, the time format is set to
"%m/%d/%y".
If an error occurs, the error indicator for the record stream is set
and the callback error function is called.
Returns
The rsettmfmt function returns no value.
1.3.17 The rsettxtch Function
Synopsis
#include <recio.h>
void rsettxtch(REC *rp, int ch);
Description
The rsettxtch function sets the text delimiter to the character ch for
the record stream pointed to by rp.
If rsettxtch is not called, the text delimiter is set by the value of
the macro RECTXTCH.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsettxtch function returns no value.
1.3.18 The rskipfld Function
Synopsis
#include <recio.h>
unsigned int rskipfld(REC *rp);
Description
The rskipfld function skips to the next field for the record stream
pointed to by rp.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns 0.
Returns
The rskipfld function returns one if the field was successfully skipped,
or zero if the field could not be skipped either because you are at the
end of the record or because an error occurred.
1.3.19 The rskipnfld Function
Synopsis
#include <recio.h>
unsigned int rskipnfld(REC *rp, unsigned int num);
Description
The rskipnfld function skips over num number of fields for the record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns 0.
Returns
The rskipfld function returns the actual number of fields skipped.
1.3.20 The ristxtfld Function
Synopsis
#include <recio.h>
unsigned ristxtfld(REC *rp);
Description
The ristxtfld function determines if the current field (the field most
recently input or output) for the record stream pointed to by rp was
quoted with the text delimiter character (provided the text delimiter
character is not the space character).
Returns
The ristxtfld function returns non-zero if the current field was quoted
and returns zero otherwise. If the text delimiter character for the stream
is the space character, the ristxtfld function always returns zero.
1.4 Character Delimited Field Output Functions
The character delimited field output functions automatically place the
field delimiter character between fields in the output.
1.4.1 The rbputi Function
Synopsis
#include <recio.h>
void rbputi(REC *rp, int base, int number);
Description
The rbputi function writes an integral number in the radix base to the
output record stream pointed to by rp. Base may be between 2 to 36.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rbputi function returns no value.
1.4.2 The rbputl Function
Synopsis
#include <recio.h>
void rbputl(REC *rp, int base, long number);
Description
The rbputl function writes an integral number in the radix base to the
output record stream pointed to by rp. Base may be between 2 to 36.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rbputl function returns no value.
1.4.3 The rbputui Function
Synopsis
#include <recio.h>
void rbputui(REC *rp, int base, unsigned int number);
Description
The rbputui function writes an unsigned integral number in the radix base to
the output record stream pointed to by rp. Base may be between 2 to 36.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rbputui function returns no value.
1.4.4 The rbputul Function
Synopsis
#include <recio.h>
void rbputul(REC *rp, int base, unsigned long number);
Description
The rbputul function writes an unsigned integral number in the radix base to
the output record stream pointed to by rp. Base may be between 2 to 36.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rbputul function returns no value.
1.4.5 The rputc Function
Synopsis
#include <recio.h>
void rputc(REC *rp, int ch);
Description
The rputc function writes a character ch to the output record stream
pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputc function returns no value.
1.4.6 The rputd Function
Synopsis
#include <recio.h>
void rputd(REC *rp, double number);
Description
The rputd function writes a floating point number to the output record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputd function returns no value.
1.4.7 The rputf Function
Synopsis
#include <recio.h>
void rputf(REC *rp, float number);
Description
The rputf function writes a floating point number to the output record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputf function returns no value.
1.4.8 The rputi Function
Synopsis
#include <recio.h>
void rputi(REC *rp, int number);
Description
The rputi function writes an integral number to the output record stream
pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputi function returns no value.
1.4.9 The rputl Function
Synopsis
#include <recio.h>
void rputl(REC *rp, long number);
Description
The rputl function writes an integral number to the output record stream
pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputl function returns no value.
1.4.10 The rputs Function
Synopsis
#include <recio.h>
void rputs(REC *rp, char *string);
Description
The rputs function writes a string of characters to the output record
stream pointed to by rp. If the text delimiter character is not the space
character, text delimiters are placed around the text.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputs function returns no value.
1.4.11 The rputt Function
Synopsis
#include <recio.h>
void rputt(REC *rp, time_t time);
Description
The rputt function writes the time to the output record stream pointed to by
rp. The format of the time is determined by the time format for the record
stream. See section 1.3.16 on how to set the time format.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputt function returns no value.
1.4.12 The rputtm Function
Synopsis
#include <recio.h>
void rputtm(REC *rp, struct tm t);
Description
The rputtm function writes out the time as specified by the contents of
struct tm t to the output record stream pointed to by rp. The format of
the time is determined by the time format for the record stream. See
section 1.3.16 on how to set the time format.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputtm function returns no value.
1.4.13 The rputui Function
Synopsis
#include <recio.h>
void rputui(REC *rp, unsigned int number);
Description
The rputui function writes an unsigned integral number to the output record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputui function returns no value.
1.4.14 The rputul Function
Synopsis
#include <recio.h>
void rputul(REC *rp, unsigned long number);
Description
The rputul function writes an unsigned integral number to the output record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rputul function returns no value.
1.5 Column Delimited Field Input Functions
The column delimited field input functions use column positions to
determine the start and end of each field.
1.5.1 The rcbgeti Function
Synopsis
#include <recio.h>
int rcbgeti(REC *rp, size_t begcol, size_t endcol, int base);
Description
The rcbgeti function gets one integral number represented by the radix
determined by the value of base and contained inclusively from column
begcol to column endcol for the input record stream pointed to by rp.
Any leading or trailing white space in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcbgeti function returns a signed integer from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcbgeti returns zero. If the record stream
is at end-of-file (end-of-file indicator set), rcbgeti returns zero. If a
previous error has occurred on the record stream that has not been cleared
(error indicator set), rcbgeti returns zero.
1.5.2 The rcbgetl Function
Synopsis
#include <recio.h>
long rcbgetl(REC *rp, size_t begcol, size_t endcol, int base);
Description
The rcbgetl function gets one integral number represented by the radix
determined by the value of base and contained inclusively from column
begcol to column endcol for the input record stream pointed to by rp.
Any leading or trailing white space in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rcbgetl function returns a signed long from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcbgetl returns zero (0L). If the record
stream is at end-of-file (end-of-file indicator set), rcbgetl returns zero
(0L). If a previous error has occurred on the record stream that has not been
cleared (error indicator set), rcbgetl returns zero (0L).
1.5.3 The rcbgetui Function
Synopsis
#include <recio.h>
unsigned int rcbgetui(REC *rp, size_t begcol, size_t endcol,
int base);
Description
The rcbgetui function gets one non-negative integral number represented
by the radix determined by the value of base and contained inclusively
from column begcol to column endcol for the input record stream pointed
to by rp. Any leading or trailing white space in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcbgetui function returns an unsigned integer from the input record
stream pointed to by rp. If begcol is beyond the end-of-record, if the
field is empty, or if there is an illegal character in the field, the
error indicator for the record stream is set, and rcbgetui returns zero. If
the record stream is at end-of-file (end-of-file indicator set), rcbgetui
returns zero. If a previous error has occurred on the record stream that has
not been cleared (error indicator set), rcbgetui returns zero.
1.5.4 The rcbgetul Function
Synopsis
#include <recio.h>
unsigned long rcbgetul(REC *rp, size_t begcol, size_t endcol,
int base);
Description
The rcbgetul function gets one non-negative integral number represented
by the radix determined by the value of base and contained inclusively
from column begcol to column endcol for the input record stream pointed
to by rp. Any leading or trailing white space in the field is ignored.
Base may be zero or in the range of 2 to 36 inclusive. If the value of
base is zero, the expected form of the integral number is described by
section 3.1.3.2 of ANSI X3.159-1989.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rcbgetul function returns an unsigned long from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcbgetul returns zero (0L). If the record
stream is at end-of-file (end-of-file indicator set), rcbgetul returns zero
(0L). If a previous error has occurred on the record stream that has not been
cleared (error indicator set), rcbgetul returns zero (0L).
1.5.5 The rcgetc Function
Synopsis
#include <recio.h>
int rcgetc(REC *rp, size_t col);
Description
The rcgetc function obtains from column position col the unsigned char
converted to an int from the input record stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns EOF.
Returns
The rcgetc function returns a character from column position col from
the input record stream pointed to by rp. If an attempt is made to read
beyond the end-of-record, the error indicator for the record stream is set,
and rcgetc returns EOF. If the record stream is at end-of-file (end-of-file
indicator set), rcgetc returns EOF. If a previous error has occurred on the
record stream that has not been cleared (error indicator set), rcgetc returns
EOF.
1.5.6 The rcgetd Function
Synopsis
#include <recio.h>
double rcgetd(REC *rp, size_t begcol, size_t endcol);
Description
The rcgetd function gets one floating point number contained inclusively
from column begcol to column endcol for the input record stream pointed to
by rp. Any leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcgetd function returns a double precision floating point number from the
input record stream pointed to by rp. If begcol is beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field, the
error indicator for the record stream is set, and rcgetd returns zero (0.0).
If the record stream is at end-of-file (end-of-file indicator set), rcgetd
returns zero (0.0). If a previous error has occurred on the record stream
that has not been cleared (error indicator set), rcgetd returns zero (0.0).
1.5.7 The rcgetf Function
Synopsis
#include <recio.h>
float rcgetf(REC *rp, size_t begcol, size_t endcol);
Description
The rcgetf function gets one floating point number contained inclusively
from column begcol to column endcol for the input record stream pointed to
by rp. Any leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcgetf function returns a single precision floating point number from the
input record stream pointed to by rp. If begcol is beyond the end-of-record,
if the field is empty, or if there is an illegal character in the field, the
error indicator for the record stream is set, and rcgetf returns zero (0.0).
If the record stream is at end-of-file (end-of-file indicator set), rcgetf
returns zero (0.0). If a previous error has occurred on the record stream
that has not been cleared (error indicator set), rcgetf returns zero (0.0).
1.5.8 The rcgeti Function
Synopsis
#include <recio.h>
int rcgeti(REC *rp, size_t begcol, size_t endcol);
Description
The rcgeti function gets one integral number contained inclusively from
column begcol to column endcol for the input record stream pointed to by
rp. Any leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcgeti function returns a signed integer from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcgeti returns zero. If the record stream
is at end-of-file (end-of-file indicator set), rcgeti returns zero. If a
previous error has occurred on the record stream that has not been cleared
(error indicator set), rcgeti returns zero.
1.5.9 The rcgetl Function
Synopsis
#include <recio.h>
long rcgetl(REC *rp, size_t begcol, size_t endcol);
Description
The rcgetl function gets one integral number contained inclusively from
column begcol to column endcol for the input record stream pointed to by
rp. Any leading or trailing white space in the field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rcgetl function returns a signed long from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcgetl returns zero (0L). If the record
stream is at end-of-file (end-of-file indicator set), rcgetl returns zero
(0L). If a previous error has occurred on the record stream that has not
been cleared (error indicator set), rcgetl returns zero (0L).
1.5.10 The rcgets Function
Synopsis
#include <recio.h>
char *rcgets(REC *rp, size_t begcol, size_t endcol);
Description
The rcgets function gets a string contained inclusively from column
begcol to column endcol for the input record stream pointed to by
rp. The rcgets function does not remove any leading or trailing
white space, nor does it remove any text delimiter characters.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns a pointer
to an empty string.
Returns
The rcgets function returns a pointer to a character array from the input
record stream pointed to by rp. If begcol is beyond the end-of-record, the
error indicator for the record stream is set, and rcgets returns a pointer to
an empty string. If the record stream is at end-of-file (eof indicator set),
rcgets returns a pointer to an empty string. If a previous error has occurred
on the record stream that has not been cleared (error indicator set), rcgets
returns a pointer to an empty string.
1.5.11 The rcgett Function
Synopsis
#include <recio.h>
time_t rcgett(REC *rp, size_t begcol, size_t endcol);
Description
The rcgett function reads a field consisting of one time of type time_t
contained inclusively from column begcol to column endcol for the input
record stream pointed to by rp. Any leading or trailing white space in
the field is ignored.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and the function returns (time_t)-1.
Returns
The rcgett function returns a time of type time_t. If an attempt is made to
read beyond the end-of-record, the error indicator for the record stream is
set, and rcgett returns (time_t)-1. If the record stream is at end-of-file
(end-of-file indicator set), rcgett returns (time_t)-1. If a previous error
has occurred on the record stream that has not been cleared (error indicator
set), rcgett returns (time_t)-1.
1.5.12 The rcgettm Function
Synopsis
#include <recio.h>
struct tm rcgettm(REC *rp, size_t begcol, size_t endcol);
Description
The rcgettm function reads a field consisting of one time of type struct tm
contained inclusively from column begcol to column endcol for the input
record stream pointed to by rp. Any leading or trailing white space in the
field is ignored.
If an error occurs, the error indicator for the record stream is set, the
callback error function is called, and an implementation defined value is
returned.
Returns
The rcgettm function returns a time of type struct tm. If an attempt is made
to read beyond the end-of-record, the error indicator for the record stream
is set, and rcgettm returns an implementation defined value. If the record
stream is at end-of-file (end-of-file indicator set), rcgettm returns an
implementation defined value. If a previous error has occurred on the
record stream that has not been cleared (error indicator set), rcgettm
returns an implementation defined value.
1.5.13 The rcgetui Function
Synopsis
#include <recio.h>
unsigned int rcgetui(REC *rp, size_t begcol, size_t endcol);
Description
The rcgetui function gets one non-negative integral number contained
inclusively from column begcol to column endcol for the input record
stream pointed to by rp. Any leading or trailing white space in the
field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero.
Returns
The rcgetui function returns an unsigned integer from the input record
stream pointed to by rp. If begcol is beyond the end-of-record, if the
field is empty, or if there is an illegal character in the field, the
error indicator for the record stream is set, and rcgetui returns zero. If
the record stream is at end-of-file (end-of-file indicator set), rcgetui
returns zero. If a previous error has occurred on the record stream that has
not been cleared (error indicator set), rcgetui returns zero.
1.5.14 The rcgetul Function
Synopsis
#include <recio.h>
unsigned long rcgetul(REC *rp, size_t begcol, size_t endcol);
Description
The rcgetul function gets one non-negative integral number contained
inclusively from column begcol to column endcol for the input record
stream pointed to by rp. Any leading or trailing white space in the
field is ignored.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the function returns zero (0L).
Returns
The rcgetul function returns an unsigned long from the input record stream
pointed to by rp. If begcol is beyond the end-of-record, if the field is
empty, or if there is an illegal character in the field, the error indicator
for the record stream is set, and rcgetul returns zero (0L). If the record
stream is at end-of-file (end-of-file indicator set), rcgetul returns zero
(0L). If a previous error has occurred on the record stream that has not
been cleared (error indicator set), rcgetul returns zero (0L).
1.6 Column Delimited Field Output Functions
The column delimited field output functions automatically place the number,
string or character between the specified columns in the output.
1.6.1 The rcbputi Function
Synopsis
#include <recio.h>
void rcbputi(REC *rp, size_t begcol, size_t endcol, int base,
int number);
Description
The rcbputi function writes an integral number in the radix base from column
begcol to column endcol of the output record stream pointed to by rp. Base
may be between 2 to 36.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcbputi function returns no value.
1.6.2 The rcbputl Function
Synopsis
#include <recio.h>
void rcbputl(REC *rp, size_t begcol, size_t endcol, int base,
long number);
Description
The rcbputl function writes an integral number in the radix base from column
begcol to column endcol of the output record stream pointed to by rp. Base
may be between 2 to 36.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcbputl function returns no value.
1.6.3 The rcbputui Function
Synopsis
#include <recio.h>
void rcbputui(REC *rp, size_t begcol, size_t endcol, int base,
unsigned int number);
Description
The rcbputui function writes an unsigned integral number in the radix base
from column begcol to column endcol of the output record stream pointed to
by rp. Base may be between 2 to 36.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcbputui function returns no value.
1.6.4 The rcbputul Function
Synopsis
#include <recio.h>
void rcbputul(REC *rp, size_t begcol, size_t endcol, int base,
unsigned long number);
Description
The rcbputul function writes an unsigned integral number in the radix base
from column begcol to column endcol of the output record stream pointed to
by rp. Base may be between 2 to 36.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcbputul function returns no value.
1.6.5 The rcputc Function
Synopsis
#include <recio.h>
void rcputc(REC *rp, size_t col, int ch);
Description
The rcputc function writes a character ch at column col of the output record
stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputc function returns no value.
1.6.6 The rcputd Function
Synopsis
#include <recio.h>
void rcputd(REC *rp, size_t begcol, size_t endcol, double number);
Description
The rcputd function writes a floating point number from column begcol to
column endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputd function returns no value.
1.6.7 The rcputf Function
Synopsis
#include <recio.h>
void rcputf(REC *rp, size_t begcol, size_t endcol, float number);
Description
The rcputf function writes a floating point number from column begcol to
column endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputf function returns no value.
1.6.8 The rcputi Function
Synopsis
#include <recio.h>
void rcputi(REC *rp, size_t begcol, size_t endcol, int number);
Description
The rcputi function writes an integral number from column begcol to column
endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputi function returns no value.
1.6.9 The rcputl Function
Synopsis
#include <recio.h>
void rcputl(REC *rp, size_t begcol, size_t endcol, long number);
Description
The rcputl function writes an integral number from column begcol to column
endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputl function returns no value.
1.6.10 The rcputs Function
Synopsis
#include <recio.h>
void rcputs(REC *rp, size_t begcol, size_t endcol, char *string);
Description
The rcputs function writes a string of characters from column begcol to
column endcol of the output record stream pointed to by rp.
If the string is too large to fit between the columns, a truncated string
is output and the callback warning function is called. The warning
indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputs function returns no value.
1.6.11 The rcputt Function
Synopsis
#include <recio.h>
void rcputt(REC *rp, size_t begcol, size_t endcol, time_t time);
Description
The rcputt function writes the time from column begcol to column endcol
of the output record stream pointed to by rp. The format of the time is
determined by the time format for the record stream. See section 1.3.16
on how to set the time format.
If the time is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputt function returns no value.
1.6.12 The rcputtm Function
Synopsis
#include <recio.h>
void rcputtm(REC *rp, size_t begcol, size_t endcol, struct tm t);
Description
The rcputtm function writes out the time as specified by the contents of
struct tm t from column begcol to column endcol of the output record
stream pointed to by rp. The format of the time is determined by the
time format for the record stream. See section 1.3.16 on how to set the
time format.
If the time is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputtm function returns no value.
1.6.13 The rcputui Function
Synopsis
#include <recio.h>
void rcputui(REC *rp, size_t begcol, size_t endcol,
unsigned int number);
Description
The rcputui function writes an unsigned integral number from column begcol to
column endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputui function returns no value.
1.6.14 The rcputul Function
Synopsis
#include <recio.h>
void rcputul(REC *rp, size_t begcol, size_t endcol,
unsigned long number);
Description
The rcputul function writes an unsigned integral number from column begcol to
column endcol of the output record stream pointed to by rp.
If the number is too large to fit between the columns, asterisks are printed
between the columns and the callback warning function is called. The
warning indicator for the record stream is set.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rcputul function returns no value.
1.7 Current Position Functions
1.7.1 The rbegcolno Function
Synopsis
#include <recio.h>
int rbegcolno(REC *rp);
Description
The rbegcolno function gets the current setting of the first column number
in the record for the record stream pointed to by rp.
Returns
The rbegcolno function returns 0 if column numbering starts with zero or
1 if column numbering starts with one.
1.7.2 The rcolno Function
Synopsis
#include <recio.h>
size_t rcolno(REC *rp);
Description
The rcolno function gets the current column number of the current record
for the record stream pointed to by rp.
Returns
The rcolno function returns the current column number of the current record
for the record stream pointed to by rp. The rcolno function returns zero
prior to the reading of the first record.
1.7.3 The rflds Function
Synopsis
#include <recio.h>
char *rflds(REC *rp);
Description
The rflds function gets a pointer to the field buffer associated with
the record stream pointed to by rp. The last field read from the current
record is stored in the field buffer. The field is terminated by a
null character.
Returns
The rflds function returns a pointer to the field buffer associated with
the record stream pointed to by rp.
1.7.4 The rfldno Function
Synopsis
#include <recio.h>
size_t rfldno(REC *rp);
Description
The rfldno function gets the number of fields that have been read from
the current record for the record stream pointed to by rp.
Returns
The rfldno function returns the number of fields that have been read from
the current record for the record stream pointed to by rp.
1.7.5 The rgetfldpos Function
Synopsis
#include <recio.h>
void rgetfldpos(REC *rp, rpos_t &pos)
Description
The rgetfldpos function stores the current value of the field position
indicator of the current record for the input stream pointed to by rp
into the object pointed to by pos. The value stored contains unspecified
information usable by the rsetfldpos function to set the field position of
the current record to the same position as when the rgetfldpos function
was called.
If an error occurs, the error indicator for the record stream is set, and
the callback error function is called.
Returns
The rgetfldpos function returns no value.
1.7.6 The rnames Function
Synopsis
#include <recio.h>
char *rnames(REC *rp);
Description
The rnames function gets a pointer to the name of the file associated
with the record stream pointed to by rp.
Returns
The rnames function returns a pointer to the name of the file associated
with the record stream pointed to by rp.
1.7.7 The rgetrec Function
Synopsis
#include <recio.h>
char *rgetrec(REC *rp);
Description
The rgetrec function gets the next record from the record stream pointed
to by rp. The rgetrec function increments the record number, clears the
field number to zero, resets the column number to rbegcolno(), and returns
a pointer to the record buffer.
Record numbering starts at one (1L). Before the first record in a record
stream is read into the record buffer, the record number is zero.
Field numbering starts at one (1). Before the first field in a record is
read into the field buffer, the field number is zero.
Column numbering starts at either zero or one, depending on the setting of
the rsetbegcolno function. Column numbering defaults to zero.
If an error occurs, the error indicator for the record stream is set,
the callback error function is called, and the rgetrec
function returns a null pointer.
If the end-of-file is reached, the end-of-file indicator for the record
stream is set and the rgetrec function returns a null pointer.
Returns
The rgetrec function returns a pointer to the record buffer if the next
record was successfully read. A null pointer is returned on either
error or end-of-file.
1.7.8 The rnumfld Function
Synopsis
#include <recio.h>
unsigned int rnumfld(REC *rp);
Description
The rnumfld function gets the number of fields in the current record for
the input record stream pointed to by rp.
If an error occurs, the error indicator for the record stream is set, and
the callback error function is called.
Returns
The rnumfld function returns the number of fields in the current record.
1.7.9 The rputrec Function
Synopsis
#include <recio.h>
void rputrec(REC *rp);
Description
The rputrec function writes the end-of-record newline character to the output
record stream pointed to by rp. The rputrec function increments the record
number, clears the field number to zero, resets the column number to either
zero or one, depending on the setting of the rsetbegcolno function.
Record numbering starts at one (1L). Before the first record in a record
stream is written, the record number is zero.
Field numbering starts at one (1). Before the first field in a record is
written, the field number is zero.
Column numbering starts at either zero or one, depending on the setting of
the rsetbegcolno function. Column numbering defaults to zero.
If an error occurs, the error indicator for the record stream is set, and
the callback error function is called.
Returns
The rputrec function returns no value.
1.7.10 The rrecs Function
Synopsis
#include <recio.h>
char *rrecs(REC *rp);
Description
The rrecs function gets a pointer to the record buffer associated with
the record stream pointed to by rp. The current record is stored in the
record buffer. The record is terminated by a null character.
Returns
The rrecs function returns a pointer to the record buffer associated with
the record stream pointed to by rp.
1.7.11 The rrecno Function
Synopsis
#include <recio.h>
long rrecno(REC *rp);
Description
The rrecno function gets the number of records that have been read from
the record stream pointed to by rp.
Returns
The rrecno function returns the number of records that have been read from
the record stream pointed to by rp.
1.7.12 The rresetrec Function
Synopsis
#include <recio.h>
void rresetrec(REC *rp);
Description
The rresetrec function resets the internals of the input stream pointed
to by rp such that the next use of a rget field function reads from the
beginning of the record buffer. It has no effect on an output stream.
Returns
The rresetrec function returns no value.
1.7.13 The rsetbegcolno Function
Synopsis
#include <recio.h>
void rsetbegcolno(REC *rp, int colno);
Description
The rsetbegcolno function sets the first column number colno for the record
stream pointed to by rp. Column numbering can start at either 0 or 1.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetbegcolno function returns no value.
1.7.14 The rsetfldpos Function
Synopsis
#include <recio.h>
void rsetfldpos(REC *rp, rpos_t &pos);
Description
The rsetfldpos function sets the field position indicator of the current
record of the input stream pointed to by rp according to the value of the
object pointed to by pos, which is a value obtained from an earlier call
to the rgetfldpos function on the same stream. If the record has changed
since the earlier call to the rgetfldpos function, the behavior of this
function is implementation dependent.
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetfldpos function returns no value.
1.7.15 The rsetfldstr Function
Synopsis
#include <recio.h>
void rsetfldstr(REC *rp, char *s);
Description
The rsetfldstr function copies the string s into the field buffer of the
record stream pointed to by rp. Any existing string in the field buffer
is overwritten. The field buffer size is increased, if necessary, to
accommodate the string.
A side effect of using the rsetfldstr function is that the error and
end-of-file indicators for the record stream are cleared (provided
rsetfldstr does not create an error).
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetfldstr function returns no value.
1.7.16 The rsetrecstr Function
Synopsis
#include <recio.h>
void rsetrecstr(REC *rp, char *s);
Description
The rsetrecstr function copies the string s into the record buffer of the
input record stream pointed to by rp. Any existing string in the record
buffer is overwritten. The record buffer size is increased, if necessary,
to accommodate the string. It has no effect on an output stream.
A side effect of using the rsetrecstr function is that the error and
end-of-file indicators for the record stream are cleared (provided
rsetrecstr does not create an error).
If an error occurs, the error indicator for the record stream is set and
the callback error function is called.
Returns
The rsetrecstr function returns no value.
1.8 Error Functions
1.8.1 The errno Macro
Synopsis
#include <errno.h>
Description
The errno macro "expands to a modifiable lvalue that has type int, the
value of which is set to a positive error number by several library
functions." -Section 4.1.3 of ANSI X3.159-1989.
1.8.2 The rclearerr Function
Synopsis
#include <recio.h>
void rclearerr(REC *rp);
Description
The rclearerr function clears the end-of-file and error indicators for
the record stream pointed to by rp.
Returns
The rclearerr function returns no value.
1.8.3 The rcxtno Function
Synopsis
#include <recio.h>
int rcxtno(REC *rp);
Description
The rcxtno function gets the context number from the record stream pointed
to by rp. Context numbers can be assigned to a record stream using the
rsetcxtno function. A zero context number indicates that the context
number has not been assigned. The recin, recout, recerr, and recprn streams
return the macro values of RECIN, RECOUT, RECERR, and RECPRN respectively.
Returns
The rcxtno function returns the context number from the record stream pointed
to by rp.
1.8.4 The reof Function
Synopsis
#include <recio.h>
int reof(REC *rp);
Description
The reof function tests the end-of-file indicator for the record stream
pointed to by rp.
Returns
The reof function returns nonzero if and only if the end-of-file indicator
is set for the record stream pointed to by rp.
1.8.5 The rerror Function
Synopsis
#include <recio.h>
int rerror(REC *rp);
Description
The rerror function tests the error indicator for the record stream
pointed to by rp.
Returns
The rerror function returns nonzero if and only if the error indicator
is set for the record stream pointed to by rp.
1.8.6 The rerrstr Function
Synopsis
#include <recio.h>
char *rerrstr(REC *rp);
Description
The rerrstr function gets the error message for the record stream pointed
to by rp. The text of the error message is implementation dependent.
Returns
The rerrstr function returns a pointer to a string containing an error
message.
1.8.7 The risvalid Function
Synopsis
#include <recio.h>
int risvalid(REC *rp);
Description
The risvalid function tests if rp is a valid pointer to a record stream.
Returns
The risvalid function returns a nonzero value if and only if rp is a
valid pointer to an open record stream.
1.8.8 The rsetcxtno Function
Synopsis
#include <recio.h>
void rsetcxtno(REC *rp, int cxtno);
Description
The rsetcxtno function sets the context number cxtno on the record stream
pointed to by rp. Assigning a context number allows a file format to be more
easily identified in the callback error function. Negative context numbers
are reserved; a zero context number indicates an that the context has not
been assigned. A macro values RECIN, RECOUT, RECERR, and RECPRN are
preassigned to the recin, recout, recerr, and recprn streams respectively.
Returns
The rsetcxtno returns no value.
1.8.9 The rseterr Function
Synopsis
#include <recio.h>
int rseterr(REC *rp, int errnum);
Description
The rseterr function sets the global error number errno to the value of
errnum if the record stream pointed to by rp is null. If rp points to
a valid record stream, the rseterr function sets the error indicator on
the record stream. The callback error function is called. If the record
stream error indicator is already set on entry to the rseterr function,
the rseterr function does nothing.
Returns
The rseterr function returns the error number. If the callback error
function corrects the error and clears the error number, the function
returns zero.
1.8.10 The rseterrfn Function
Synopsis
#include <recio.h>
void rseterrfn(void(*rerrfn)(REC *rp));
Description
The rseterrfn function registers the callback error function rerrfn for the
record stream pointed to by rp.
Returns
The rseterrfn function returns no value. The callback error function rerrfn
returns no value.
1.8.11 The rstrerror Function
Synopsis
#include <recio.h>
char *rstrerror(int errnum);
Description
The rstrerror function maps the error number in errnum to an error
message string. The error number and the text of the error message
are implementation dependent. (To map errno to an error string, use
the strerror function.)
Returns
The rstrerror function returns a pointer to a string containing an
error message.
1.9 Warning Functions
1.9.1 The rclearwarn Function
Synopsis
#include <recio.h>
void rclearwarn(REC *rp);
Description
The rclearwarn function clears the warning indicator for the record stream
pointed to by rp.
Returns
The rclearwarn function returns no value.
1.9.2 The rsetwarn Function
Synopsis
#include <recio.h>
int rsetwarn(REC *rp, int warnum);
Description
The rsetwarn function sets the warning indicator on the record stream
pointed to by rp. The callback warning function is called (if registered).
Returns
The rsetwarn function returns the warning number. If the callback warning
function modifies the warning number, the function returns the modified
warning number.
1.9.3 The rsetwarnfn Function
Synopsis
#include <recio.h>
void rsetwarnfn(void(*rwarnfn)(REC *rp));
Description
The rsetwarnfn function registers the callback warning function rwarnfn for
the record stream pointed to by rp.
Returns
The rsetwarnfn function returns no value. The callback warning function
rwarnfn returns no value.
1.9.4 The rstrwarning Function
Synopsis
#include <recio.h>
char *rstrwarning(int warnum);
Description
The rstrwarning function maps the warning number warnum to an warning
message string. The warning number and the text of the warning message
are implementation dependent.
Returns
The rstrwarning function returns a pointer to a string containing an
warning message.
1.9.5 The rwarning Function
Synopsis
#include <recio.h>
int rwarning(REC *rp);
Description
The rwarning function tests the warning indicator for the record stream
pointed to by rp.
Returns
The rwarning function returns nonzero if and only if the warning indicator
is set for the record stream pointed to by rp.
1.9.6 The rwarnstr Function
Synopsis
#include <recio.h>
char *rwarnstr(REC *rp);
Description
The rwarnstr function gets the warning message for the record stream pointed
to by rp. The text of the warning message is implementation dependent.
Returns
The rwarnstr function returns a pointer to a string containing an warning
message.
2.0 PORTABILITY ISSUES
The first six characters of this function are common to another function.
Ref 3.1.2 of ANSI X3.159-1989. (1.2.1, 1.2.2, 1.2.4, 1.3.3, 1.3.4, 1.3.15,
1.5.1-1.5.4, 1.5.11-1.5.14, 1.6.1-1.6.4, 1.6.11-1.6.14, 1.7.15, 1.8.9,
1.8.10, 1.9.2, 1.9.3)
References are not implemented in ANSI X3.159-1989, but are part of C++.
They can be reasonably simulated in C (for functions that don't have a
variable number of arguments) by use of a macro that inserts the & into the
call. (1.7.5, 1.7.14)
3.0 REFERENCES
1. ANSI X3.159-1989. American National Standard for Information Systems -
Programming Language - C. American National Standards Institute,
11 West 42nd Street, New York, NY 10036, 1990.
4.0 INDEX
errno macro ............ 1.8.1
FLDBUFSIZ macro ........ 1.1.3, 1.2.4
rbegcolno function ..... 1.7.1, 1.7.7
rbgeti function ........ 1.3.1
rbgetl function ........ 1.3.2
rbgetui function ....... 1.3.3
rbgetul function ....... 1.3.4
rbputi function ........ 1.4.1
rbputl function ........ 1.4.2
rbputui function ....... 1.4.3
rbputul function ....... 1.4.4
rcbgeti function ....... 1.5.1
rcbgetl function ....... 1.5.2
rcbgetui function ...... 1.5.3
rcbgetul function ...... 1.5.4
rcbputi function ....... 1.6.1
rcbputl function ....... 1.6.2
rcbputui function ...... 1.6.3
rcbputul function ...... 1.6.4
rcgetc function ........ 1.5.5
rcgetd function ........ 1.5.6
rcgetf function ........ 1.5.7
rcgeti function ........ 1.5.8
rcgetl function ........ 1.5.9
rcgets function ........ 1.5.10
rcgett function ........ 1.5.11
rcgettm function ....... 1.5.12
rcgetui function ....... 1.5.13
rcgetul function ....... 1.5.14
rclearerr function ..... 1.8.2
rclearwarn function .... 1.9.1
rclose function ........ 1.2.1
rcloseall function ..... 1.2.2
rcolno function ........ 1.7.2
rcputc function ........ 1.6.5
rcputd function ........ 1.6.6
rcputf function ........ 1.6.7
rcputi function ........ 1.6.8
rcputl function ........ 1.6.9
rcputs function ........ 1.6.10
rcputt function ........ 1.6.11
rcputtm function ....... 1.6.12
rcputui function ....... 1.6.13
rcputul function ....... 1.6.14
rcxtno function ........ 1.8.3
REC object ............. 1.1.2
recin expression ....... 1.1.4
RECBUFSIZ macro ........ 1.1.3, 1.2.5
RECFLDCH macro ......... 1.1.3, 1.3.15
RECTXTCH macro ......... 1.1.3, 1.3.17
reof function .......... 1.8.4
rerror function ........ 1.8.5
rerrstr function ....... 1.8.6
rflds function ......... 1.7.3
rfldno function ........ 1.7.4
rgetc function ......... 1.3.5
rgetd function ......... 1.3.6
rgetf function ......... 1.3.7
rgetfldpos function .... 1.7.5
rgeti function ......... 1.3.8
rgetl function ......... 1.3.9
rgetrec function ....... 1.7.7
rgets function ......... 1.3.10
rgett function ......... 1.3.11
rgettm function ........ 1.3.12
rgetui function ........ 1.3.13
rgetul function ........ 1.3.14
ristxtfld function ..... 1.3.20
risvalid function ...... 1.8.7
rnames function ........ 1.7.6
rnumfld function ....... 1.7.8
ropen function ........ 1.2.3
ROPEN_MAX macro ........ 1.1.3
rputc function ......... 1.4.5
rputd function ......... 1.4.6
rputf function ......... 1.4.7
rputi function ......... 1.4.8
rputl function ......... 1.4.9
rputrec function ....... 1.7.9
rputs function ......... 1.4.10
rputt function ......... 1.4.11
rputtm function ........ 1.4.12
rputui function ........ 1.4.13
rputul function ........ 1.4.14
rrecs function ......... 1.7.10
rrecno function ........ 1.7.11
rresetstr function ..... 1.7.12
rsetbegcolno function .. 1.7.7, 1.7.13
rsetcxtno function ..... 1.8.8
rseterr function ....... 1.8.9
rseterrfn function ..... 1.8.10
rsetfldch function ..... 1.3.15
rsetfldpos function .... 1.7.14
rsetfldsiz function .... 1.2.4
rsetfldstr function .... 1.7.15
rsetrecsiz function .... 1.2.5
rsetrecstr function .... 1.7.16
rsettmfmt function ..... 1.3.16
rsettxtch function ..... 1.3.17
rsetwarn function ...... 1.9.2
rsetwarnfn function .... 1.9.3
rskipfld function ..... 1.3.18
rskipnfld function ..... 1.3.19
rstrerror function ..... 1.8.11
rstrwarning function ... 1.9.4
rwarning function ...... 1.9.5
rwarnstr function ...... 1.9.6
